---
layout: api
page_title: ACL Policies - HTTP API
description: The /acl/policy endpoints are used to configure and manage ACL policies.
---

# ACL Policies HTTP API

The `/acl/policies` and `/acl/policy/` endpoints are used to manage ACL policies.
For more details about ACLs, please see the [ACL Guide](/nomad/tutorials/access-control).

## List Policies

This endpoint lists all ACL policies. This lists the policies that have been replicated
to the region, and may lag behind the authoritative region.

| Method | Path               | Produces           |
| ------ | -----   ---------- | ------------------ |
| `GET`  | `/v1/acl/policies` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries), [consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | Consistency Modes | ACL Required                                                                                                                     |
| ---------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `YES`            | `all`             | `management` for all policies.<br />Output when given a non-management token will be limited to the policies on the token itself |

### Parameters

- `prefix` `(string: "")` - Specifies a string to filter ACL policies based on
  a name prefix. This is specified as a query string parameter.

### Sample Request

```shell-session
$ curl \
    https://localhost:4646/v1/acl/policies
```

```shell-session
$ curl \
    https://localhost:4646/v1/acl/policies?prefix=prod
```

### Sample Response

```json
[
  {
    "Name": "foo",
    "Description": "",
    "CreateIndex": 12,
    "ModifyIndex": 13
  }
]
```

## Create or Update Policy

This endpoint creates or updates an ACL Policy. This request is always forwarded to the
authoritative region.

| Method | Path                          | Produces       |
| ------ | ----------------------------- | -------------- |
| `POST` | `/v1/acl/policy/:policy_name` | `(empty body)` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO`             | `management` |

### Parameters

- `Name` `(string: <required>)` - Specifies the name of the policy.
  Creates the policy if the name does not exist, otherwise updates the existing policy.

- `Description` `(string: <optional>)` - Specifies a human readable description.

- `Rules` `(string: <required>)` - Specifies the Policy rules in HCL or JSON format.

- `JobACL` `(JobACL: <optional>)` - Associates the policy with a given job,
  group, or task. Refer to [Workload Associated ACL
  Policies][concepts_workload_identity_acl] for more information.

  - `Namespace` `(string: <optional>)` - Attach the policy to the job in this
    namespace.  Required if `JobID` is set.

  - `JobID` `(string)` - Attach the policy to this job. Required to use `JobACL`.

  - `Group` `(string: <optional>)` - Attach the policy to this group within the
    job.  Required if `Task` is set.

  - `Task` `(string: <optional>)` - Attach the policy to this task within the job.

### Sample Payload

```json
{
  "Name": "my-policy",
  "Description": "This is a great policy",
  "Rules": "",
  "JobACL": {
    "Namespace": "default",
    "JobID": "example"
  }
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/acl/policy/my-policy
```

## Read Policy

This endpoint reads an ACL policy with the given name. This queries the policy that have been
replicated to the region, and may lag behind the authoritative region.

| Method | Path                          | Produces           |
| ------ | ----------------------------- | ------------------ |
| `GET`  | `/v1/acl/policy/:policy_name` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries), [consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | Consistency Modes | ACL Required                                |
| ---------------- | ----------------- | ------------------------------------------- |
| `YES`            | `all`             | `management` or token with access to policy |

### Sample Request

```shell-session
$ curl \
    https://localhost:4646/v1/acl/policy/foo
```

### Sample Response

```json
{
  "Name": "foo",
  "Rules": "",
  "Description": "",
  "CreateIndex": 12,
  "ModifyIndex": 13
}
```

## Read Self Policy

This endpoint reads the ACL policies associated with the current workload
identity or any authenticated request.

| Method | Path                  | Produces           |
|--------|-----------------------|--------------------|
| `GET`  | `/v1/acl/policy/self` | `application/json` |

This table shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries), [consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | Consistency Modes | ACL Required                    |
|------------------|-------------------|---------------------------------|
| `YES`            | `all`             | Any valid Workload Identity JWT |

### Sample Request

```shell-session
$ curl --header "X-Nomad-Token: eyJhbGciOiJSUzI1NiIsImtpZCI6ImJiMmUwYjI5LTIyZTYtYjk0My0yN2M1LThkYmNmMjc5ODM0MCIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJub21hZHByb2plY3QuaW8iLCJpYXQiOjE3NDM2OTI5NzksImp0aSI6IjJmOWI3ZGRmLWU1M2ItZGMxNS1kMzU4LTAyMDk5NjE1NThlMyIsIm5iZiI6MTc0MzY5Mjk3OSwibm9tYWRfYWxsb2NhdGlvbl9pZCI6IjhjMGJjMWFjLWRlMzMtYTNlYi03YWUwLTZiZjM3OGY5YzcxYiIsIm5vbWFkX2pvYl9pZCI6Im5vbWFkIiwibm9tYWRfbmFtZXNwYWNlIjoiZGVmYXVsdCIsIm5vbWFkX3Rhc2siOiJzZXJ2ZXIiLCJzdWIiOiJnbG9iYWw6ZGVmYXVsdDpub21hZDpub21hZDpzZXJ2ZXI6ZGVmYXVsdCJ9.IDZWTqGWRURDwI5OvO3LLjCsU1qzg6LEG4q5S7CfZawUXzMqAOoYajI_nynOGJp2aU77MqUyJmdFtrIBMoQnIxclEwNl9DkhfOrgjBsWefn9JqKEpORGD-0OLzaoYUgbu0k6aXCNktfpvHZN5uUsfL6nLOG-osQvHn9ZdboT31tjp1v6d-MfP96ZLG0NrXgLWMfwan2AAzuqMabIS9iO6OrZDNp2-TeeY_sqM-7sNEgfDo33GAeyhqTi8CAZhsDOv4wtJuFfMhrsbb33wHdAiltjXlafBtncMMaLHr07gbLvOMfty2_193i4Yi3H2PgPr7c4BYHoXyQJhFchDyYmFA" \
    https://localhost:4646/v1/acl/policy/self
```

### Sample Response

```json
[
  {
    "CreateIndex": 22,
    "Description": "",
    "Hash": "SmmKR0rW0WA0Bfpk7m3D8wqgrL0dtkY3DwAucF9YN4Y=",
    "JobACL": {
      "Group": "nomad",
      "JobID": "nomad",
      "Namespace": "default",
      "Task": ""
    },
    "ModifyIndex": 22,
    "Name": "nomad-policy"
  }
]
```

## Delete Policy

This endpoint deletes the named ACL policy. This request is always forwarded to the
authoritative region.

| Method   | Path                          | Produces       |
| -------- | ----------------------------- | -------------- |
| `DELETE` | `/v1/acl/policy/:policy_name` | `(empty body)` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO`             | `management` |

### Parameters

- `policy_name` `(string: <required>)` - Specifies the policy name to delete.

### Sample Request

```shell-session
$ curl \
    --request DELETE \
    https://localhost:4646/v1/acl/policy/foo
```

[concepts_workload_identity_acl]: /nomad/docs/concepts/workload-identity#workload-associated-acl-policies
